---
title: MediaLibrary
description: A library that provides access to the device's media library.
sourceCodeUrl: 'https://github.com/expo/expo/tree/sdk-53/packages/expo-media-library'
packageName: 'expo-media-library'
iconUrl: '/static/images/packages/expo-media-library.png'
platforms: ['android', 'ios', 'tvos']
---

import APISection from '~/components/plugins/APISection';
import { APIInstallSection } from '~/components/plugins/InstallSection';
import { AndroidPermissions, IOSPermissions } from '~/components/plugins/permissions';
import {
  ConfigReactNative,
  ConfigPluginExample,
  ConfigPluginProperties,
} from '~/ui/components/ConfigSection';
import { SnackInline } from '~/ui/components/Snippet';

`expo-media-library` provides access to the user's media library, allowing them to access their existing images and videos from your app, as well as save new ones. You can also subscribe to any updates made to the user's media library.

> **warning** Android allows full access to the media library (which is the purpose of this package) only for applications needing broad access to photos. See [Details on Google Play's Photo and Video Permissions policy](https://support.google.com/googleplay/android-developer/answer/14115180).

## Installation

<APIInstallSection />

## Configuration in app config

You can configure `expo-media-library` using its built-in [config plugin](/config-plugins/introduction/) if you use config plugins in your project ([Continuous Native Generation (CNG)](/workflow/continuous-native-generation/)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does **not** use CNG, then you'll need to manually configure the library.

<ConfigPluginExample>

```json
{
  "expo": {
    "plugins": [
      [
        "expo-media-library",
        {
          "photosPermission": "Allow $(PRODUCT_NAME) to access your photos.",
          "savePhotosPermission": "Allow $(PRODUCT_NAME) to save photos.",
          "isAccessMediaLocationEnabled": true
        }
      ]
    ]
  }
}
```

</ConfigPluginExample>

<ConfigPluginProperties
  properties={[
    {
      name: 'photosPermission',
      platform: 'ios',
      description:
        'Sets the iOS `NSPhotoLibraryUsageDescription` permission message in **Info.plist**.',
      default: '"Allow $(PRODUCT_NAME) to access your photos."',
    },
    {
      name: 'savePhotosPermission',
      platform: 'ios',
      description:
        'Sets the iOS `NSPhotoLibraryAddUsageDescription` permission message in **Info.plist**.',
      default: '"Allow $(PRODUCT_NAME) to save photos."',
    },
    {
      name: 'preventAutomaticLimitedAccessAlert',
      platform: 'ios',
      description:
        'Prevents the automatic limited access alert from being shown when the user has limited access to the photo library. Useful for apps that want to access only the limited photo library without having iOS forcibly show the alert.',
      default: 'false',
    },
    {
      name: 'isAccessMediaLocationEnabled',
      platform: 'android',
      description:
        'Sets whether or not to request the `ACCESS_MEDIA_LOCATION` permission on Android.',
      default: 'false',
    },
  ]}
/>

<ConfigReactNative>

If you're not using Continuous Native Generation ([CNG](/workflow/continuous-native-generation/)) or you're using native **android** and **ios** projects manually, then you need to add following permissions and configuration to your native projects:

**Android**

- To access asset location (latitude and longitude EXIF tags), add `ACCESS_MEDIA_LOCATION` permission to your project's **android/app/src/main/AndroidManifest.xml**:

  ```xml
  <uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
  ```

- [Scoped storage](https://developer.android.com/training/data-storage#scoped-storage) is available from Android 10. To make `expo-media-library` work with scoped storage, you need to add the following configuration to your **android/app/src/main/AndroidManifest.xml**:

  ```xml
  <manifest ... >
    <application android:requestLegacyExternalStorage="true" ...>
  </manifest>
  ```

**iOS**

- Add `NSPhotoLibraryUsageDescription`, and `NSPhotoLibraryAddUsageDescription` keys to your project's **ios/[app]/Info.plist**:

  ```xml
  <key>NSPhotoLibraryUsageDescription</key>
  <string>Give $(PRODUCT_NAME) permission to access your photos</string>
  <key>NSPhotoLibraryAddUsageDescription</key>
  <string>Give $(PRODUCT_NAME) permission to save photos</string>
  ```

</ConfigReactNative>

## Usage

<SnackInline label='Fetching albums and displaying assets' dependencies={['expo-media-library']}>

{/* prettier-ignore */}
```jsx
import { useState, useEffect } from 'react';
import { Button, Text, SafeAreaView, ScrollView, StyleSheet, Image, View, Platform } from 'react-native';
import * as MediaLibrary from 'expo-media-library';

export default function App() {
  const [albums, setAlbums] = useState(null);
  const [permissionResponse, requestPermission] = MediaLibrary.usePermissions();

  async function getAlbums() {
    if (permissionResponse.status !== 'granted') {
      await requestPermission();
    }
    const fetchedAlbums = await MediaLibrary.getAlbumsAsync({
      includeSmartAlbums: true,
    });
    setAlbums(fetchedAlbums);
  }

  return (
    <SafeAreaView style={styles.container}>
      <Button onPress={getAlbums} title="Get albums" />
      <ScrollView>
        {albums && albums.map((album) => <AlbumEntry album={album} />)}
      </ScrollView>
    </SafeAreaView>
  );
}

function AlbumEntry({ album }) {
  const [assets, setAssets] = useState([]);

  useEffect(() => {
    async function getAlbumAssets() {
      const albumAssets = await MediaLibrary.getAssetsAsync({ album });
      setAssets(albumAssets.assets);
    }
    getAlbumAssets();
  }, [album]);

  return (
    <View key={album.id} style={styles.albumContainer}>
      <Text>
        {album.title} - {album.assetCount ?? 'no'} assets
      </Text>
      <View style={styles.albumAssetsContainer}>
        {assets && assets.map((asset) => (
          <Image source={{ uri: asset.uri }} width={50} height={50} />
        ))}
      </View>
    </View>
  );
}

/* @hide const styles = StyleSheet.create({ ... }); */
const styles = StyleSheet.create({
  container: {
    flex: 1,
    gap: 8,
    justifyContent: 'center',
    ...Platform.select({
      android: {
        paddingTop: 40,
      },
    }),
  },
  albumContainer: {
    paddingHorizontal: 20,
    marginBottom: 12,
    gap: 4,
  },
  albumAssetsContainer: {
    flexDirection: 'row',
    flexWrap: 'wrap',
  },
});
/* @end */
````

</SnackInline>

## API

```js
import * as MediaLibrary from 'expo-media-library';
```

<APISection packageName="expo-media-library" apiName="MediaLibrary" />

## Permissions

### Android

The following permissions are added automatically through this library's **AndroidManifest.xml**:

<AndroidPermissions
  permissions={[
    'READ_EXTERNAL_STORAGE',
    'WRITE_EXTERNAL_STORAGE',
    'READ_MEDIA_IMAGES',
    'READ_MEDIA_VIDEO',
    'READ_MEDIA_AUDIO',
    'READ_MEDIA_VISUAL_USER_SELECTED',
  ]}
/>

### iOS

The following usage description keys are used by this library:

<IOSPermissions
  permissions={['NSPhotoLibraryUsageDescription', 'NSPhotoLibraryAddUsageDescription']}
/>
